home *** CD-ROM | disk | FTP | other *** search
FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) NNNNAAAAMMMMEEEE filebuf - buffer for file I/O. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_iiii_oooo_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>> _tttt_yyyy_pppp_eeee_dddd_eeee_ffff _llll_oooo_nnnn_gggg _ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff_,,,, _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_;;;; _cccc_llll_aaaa_ssss_ssss _iiii_oooo_ssss _{{{{ _pppp_uuuu_bbbb_llll_iiii_cccc_:::: _eeee_nnnn_uuuu_mmmm _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr _{{{{ _bbbb_eeee_gggg_,,,, _cccc_uuuu_rrrr_,,,, _eeee_nnnn_dddd _}}}}_;;;; _eeee_nnnn_uuuu_mmmm _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee _{{{{ _iiii_nnnn_,,,, _oooo_uuuu_tttt_,,,, _aaaa_tttt_eeee_,,,, _aaaa_pppp_pppp_,,,, _tttt_rrrr_uuuu_nnnn_cccc_,,,, _nnnn_oooo_cccc_rrrr_eeee_aaaa_tttt_eeee_,,,, _nnnn_oooo_rrrr_eeee_pppp_llll_aaaa_cccc_eeee _}}}} _;;;; _////_//// _aaaa_nnnn_dddd _llll_oooo_tttt_ssss _oooo_ffff _oooo_tttt_hhhh_eeee_rrrr _ssss_tttt_uuuu_ffff_ffff_,,,, _ssss_eeee_eeee _iiii_oooo_ssss_((((_3333_CCCC_++++_++++_)))) _...._...._.... _}}}} _;;;; _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ffff_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>> _cccc_llll_aaaa_ssss_ssss _ffff_iiii_llll_eeee_bbbb_uuuu_ffff _:::: _pppp_uuuu_bbbb_llll_iiii_cccc _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff _{{{{ _pppp_uuuu_bbbb_llll_iiii_cccc_:::: _ssss_tttt_aaaa_tttt_iiii_cccc _cccc_oooo_nnnn_ssss_tttt _iiii_nnnn_tttt _oooo_pppp_eeee_nnnn_pppp_rrrr_oooo_tttt _;;;; _////_**** _dddd_eeee_ffff_aaaa_uuuu_llll_tttt _pppp_rrrr_oooo_tttt_eeee_cccc_tttt_iiii_oooo_nnnn _ffff_oooo_rrrr _oooo_pppp_eeee_nnnn _****_//// _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_)))) _;;;; _~~~~_ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_)))) _;;;; _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_iiii_nnnn_tttt _dddd_))))_;;;; _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_iiii_nnnn_tttt _dddd_,,,, _cccc_hhhh_aaaa_rrrr_**** _pppp_,,,, _iiii_nnnn_tttt _llll_eeee_nnnn_)))) _;;;; _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_**** _aaaa_tttt_tttt_aaaa_cccc_hhhh_((((_iiii_nnnn_tttt _dddd_)))) _;;;; _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_**** _cccc_llll_oooo_ssss_eeee_((((_))))_;;;; _iiii_nnnn_tttt _ffff_dddd_((((_))))_;;;; _iiii_nnnn_tttt _iiii_ssss______oooo_pppp_eeee_nnnn_((((_))))_;;;; _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_**** _oooo_pppp_eeee_nnnn_((((_cccc_hhhh_aaaa_rrrr _****_nnnn_aaaa_mmmm_eeee_,,,, _iiii_nnnn_tttt _oooo_mmmm_oooo_dddd_eeee_,,,, _iiii_nnnn_tttt _pppp_rrrr_oooo_tttt_====_oooo_pppp_eeee_nnnn_pppp_rrrr_oooo_tttt_)))) _;;;; _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff_,,,, _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr_,,,, _iiii_nnnn_tttt _oooo_mmmm_oooo_dddd_eeee_)))) _;;;; _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss _ssss_eeee_eeee_kkkk_pppp_oooo_ssss_((((_ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_,,,, _iiii_nnnn_tttt _oooo_mmmm_oooo_dddd_eeee_)))) _;;;; _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff_****_ssss_eeee_tttt_bbbb_uuuu_ffff_((((_cccc_hhhh_aaaa_rrrr_**** _pppp_,,,, _iiii_nnnn_tttt _llll_eeee_nnnn_)))) _;;;; _iiii_nnnn_tttt _ssss_yyyy_nnnn_cccc_((((_)))) _;;;; _}}}}_;;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _ffff_iiii_llll_eeee_bbbb_uuuu_ffffs specialize _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffffs to use a file as a source or sink of characters. Characters are consumed by doing writes to the file, and are produced by doing reads. When the file is seekable, a _ffff_iiii_llll_eeee_bbbb_uuuu_ffff allows seeks. At least 4 characters of putback are guaranteed. When the file permits reading and writing, the _ffff_iiii_llll_eeee_bbbb_uuuu_ffff permits both storing and fetching. No special action is required between gets and puts (unlike stdio). A _ffff_iiii_llll_eeee_bbbb_uuuu_ffff that is connected to a file descriptor is said to be _oooo_pppp_eeee_nnnn. Files are opened by default with a protection mode of _oooo_pppp_eeee_nnnn_pppp_rrrr_oooo_tttt, which is 0644. The _r_e_s_e_r_v_e _a_r_e_a (or buffer, see _ssss_bbbb_uuuu_ffff_...._pppp_uuuu_bbbb(3C++) and _ssss_bbbb_uuuu_ffff_...._pppp_rrrr_oooo_tttt(3C++)) is allocated automatically if one is not specified explicitly with a constructor or a call to _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_)))). _ffff_iiii_llll_eeee_bbbb_uuuu_ffffs can also be made _uuuu_nnnn_bbbb_uuuu_ffff_ffff_eeee_rrrr_eeee_dddd with certain arguments to the constructor or _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_)))), in which case a system call is made for each character that is read or written. The _gggg_eeee_tttt PPPPaaaaggggeeee 1111 FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) and _pppp_uuuu_tttt pointers into the reserve area are conceptually tied together; they behave as a single pointer. Therefore, the descriptions below refer to a single get/put pointer. In the descriptions below, assume: - _f is a _ffff_iiii_llll_eeee_bbbb_uuuu_ffff. - _p_f_b is a _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_****. - _p_s_b is a _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff_****. - _i, _d, _l_e_n, and _p_r_o_t are _iiii_nnnn_tttts. - _n_a_m_e and _p_t_r are _cccc_hhhh_aaaa_rrrr_****s. - _m_o_d_e is an _iiii_nnnn_tttt representing an _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee. - _o_f_f is a _ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff. - _p and _p_o_s are _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss's. - _d_i_r is a _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr. Constructors: _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_)))) Constructs an initially closed _ffff_iiii_llll_eeee_bbbb_uuuu_ffff. _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_d_)))) Constructs a _ffff_iiii_llll_eeee_bbbb_uuuu_ffff connected to file descriptor _d. _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_((((_d_,,,, _p_,,,, _l_e_n_)))) Constructs a _ffff_iiii_llll_eeee_bbbb_uuuu_ffff connected to file descriptor _d and initialized to use the reserve area starting at _p and containing _l_e_n bytes. If _p is null or _l_e_n is zero or less, the _ffff_iiii_llll_eeee_bbbb_uuuu_ffff will be unbuffered. Members: _p_f_b_====_f_...._aaaa_tttt_tttt_aaaa_cccc_hhhh_((((_d_)))) Connects _f to an open file descriptor, _d. _aaaa_tttt_tttt_aaaa_cccc_hhhh_((((_)))) normally returns _&&&&_f, but returns 0 if _f is already open. _p_f_b_====_f_...._cccc_llll_oooo_ssss_eeee_((((_)))) Flushes any waiting output, closes the file descriptor, and disconnects _f. Unless an error occurs, _f's error state will be cleared. _cccc_llll_oooo_ssss_eeee_((((_)))) returns _&&&&_f unless errors occur, in which case it returns _0000. Even if errors occur, _cccc_llll_oooo_ssss_eeee_((((_)))) leaves the file descriptor and _f closed. _i_====_f_...._ffff_dddd_((((_)))) Returns _i, the file descriptor _f is connected to. If _f is closed, _i is _EEEE_OOOO_FFFF. _i_====_f_...._iiii_ssss______oooo_pppp_eeee_nnnn_((((_)))) Returns non-zero when _f is connected to a file descriptor, and zero otherwise. _p_f_b_====_f_...._oooo_pppp_eeee_nnnn_((((_n_a_m_e_,,,, _m_o_d_e_,,,, _p_r_o_t_)))) Opens file _n_a_m_e and connects _f to it. If the file does not already exist, an attempt is made to create it with protection mode _p_r_o_t, PPPPaaaaggggeeee 2222 FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) unless _iiii_oooo_ssss_::::_::::_nnnn_oooo_cccc_rrrr_eeee_aaaa_tttt_eeee is specified in _m_o_d_e. By default, _p_r_o_t is _ffff_iiii_llll_eeee_bbbb_uuuu_ffff_::::_::::_oooo_pppp_eeee_nnnn_pppp_rrrr_oooo_tttt, which is 0644. Failure occurs if _f is already open. _oooo_pppp_eeee_nnnn_((((_)))) normally returns _&&&&_f, but if an error occurs it returns 0. The members of _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee are bits that may be or'ed together. (Because the or'ing returns an _iiii_nnnn_tttt, _oooo_pppp_eeee_nnnn_((((_)))) takes an _iiii_nnnn_tttt rather than an _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee argument.) The meanings of these bits in _m_o_d_e are described in detail in _ffff_ssss_tttt_rrrr_eeee_aaaa_mmmm(3C++). _p_====_f_...._ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_o_f_f_,,,, _d_i_r_,,,, _m_o_d_e_)))) Moves the get/put pointer as designated by _o_f_f and _d_i_r. It may fail if the file that _f is attached to does not support seeking, or if the attempted motion is otherwise invalid (such as attempting to seek to a position before the beginning of file). _o_f_f is interpreted as a count relative to the place in the file specified by _d_i_r as described in _ssss_bbbb_uuuu_ffff_...._pppp_uuuu_bbbb(3C++). _m_o_d_e is ignored. _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_)))) returns _p, the new position, or _EEEE_OOOO_FFFF if a failure occurs. The position of the file after a failure is undefined. _p_====_f_...._ssss_eeee_eeee_kkkk_pppp_oooo_ssss_((((_p_o_s_,,,, _m_o_d_e_)))) Moves the file to a position _p_o_s as described in _ssss_bbbb_uuuu_ffff_...._pppp_uuuu_bbbb(3C++). _m_o_d_e is ignored. _ssss_eeee_eeee_kkkk_pppp_oooo_ssss_((((_)))) normally returns _p_o_s, but on failure it returns _EEEE_OOOO_FFFF. _p_s_b_====_f_...._ssss_eeee_tttt_bbbb_uuuu_ffff_((((_p_t_r_,,,, _l_e_n_)))) Sets up the reserve area as _l_e_n bytes beginning at _p_t_r. If _p_t_r is null or _l_e_n is less than or equal to 0, _f will be unbuffered. _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_)))) normally returns _&&&&_f. However, if _f is open and a buffer has been allocated, no changes are made to the reserve area or to the buffering status, and _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_)))) returns 0. _i_====_f_...._ssss_yyyy_nnnn_cccc_((((_)))) Attempts to force the state of the get/put pointer of _ffff to agree (be synchronized) with the state of the file _f_...._ffff_dddd_((((_)))). This means it may write characters to the file if some have been buffered for output or attempt to reposition (seek) the file if characters have been read and buffered for input. Normally, _ssss_yyyy_nnnn_cccc_((((_)))) returns 0, but it returns _EEEE_OOOO_FFFF if synchronization is not possible. Sometimes it is necessary to guarantee that certain characters are written together. To do this, the program should use _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_)))) (or a constructor) to guarantee that the reserve area is at least as large as the number of characters that must be written together. It can then call _ssss_yyyy_nnnn_cccc_((((_)))), then store the characters, then call _ssss_yyyy_nnnn_cccc_((((_)))) again. CCCCAAAAVVVVEEEEAAAATTTTSSSS _aaaa_tttt_tttt_aaaa_cccc_hhhh_((((_)))) and the constructors should test if the file descriptor they are given is open, but I can't figure out a portable way to do that. There is no way to force atomic reads. PPPPaaaaggggeeee 3333 FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) FFFFIIIILLLLEEEEBBBBUUUUFFFF((((3333CCCC++++++++)))) The UNIX system does not usually report failures of seek (e.g., on a tty), so a filebuf does not either. SSSSEEEEEEEE AAAALLLLSSSSOOOO _ssss_bbbb_uuuu_ffff_...._pppp_uuuu_bbbb(3C++), _ssss_bbbb_uuuu_ffff_...._pppp_rrrr_oooo_tttt(3C++), and _ffff_ssss_tttt_rrrr_eeee_aaaa_mmmm(3C++). PPPPaaaaggggeeee 4444 
